Skip to content

Add Architecture Decision Record (ADR) system #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add Architecture Decision Record (ADR) system #212

Copilot wants to merge 3 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Jan 1, 2026 •
edited
Loading

Establishes systematic documentation of architectural decisions to preserve context and rationale for current and future contributors.

Structure

  • docs/adr/: Contains all ADRs with sequential 4-digit numbering
  • 0000-adr-template.md: Reusable template following Nygard format (Status, Context, Decision, Consequences)
  • docs/adr/README.md: Index table, creation instructions, and ADR documentation
  • 0001-use-architecture-decision-records.md: Initial ADR documenting this decision

Integration

Main README now links to ADR system under Documentation section.

Usage

# Create new ADR
cp docs/adr/0000-adr-template.md docs/adr/0002-your-decision.md
# Edit, update index table in docs/adr/README.md, submit PR

ADRs are immutable once accepted. Supersede with new ADRs rather than editing existing ones.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • astral.sh
    • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>Start to maintain an ADR</issue_title>
<issue_description>Architecture Decision Record (ADR)</issue_description>

Comments on the Issue (you are @copilot in this section)

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

@tschm
Add Architecture Decision Records (ADR) system to project
e76dc80 
Co-authored-by: tschm <2046079+tschm@users.noreply.github.com>
@tschm tschm requested review from HarryCampion and Copilot and removed request for Copilot January 1, 2026 17:56
@tschm
Clarify ADR naming conventions and use consistent examples
df5140f 
Co-authored-by: tschm <2046079+tschm@users.noreply.github.com>
@tschm tschm marked this pull request as ready for review January 1, 2026 17:57
Copilot AI changed the title [WIP] Add initial architecture decision record Add Architecture Decision Record (ADR) system Jan 1, 2026
Copilot AI requested a review from tschm January 1, 2026 17:58
Copilot AI reviewed Jan 1, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR establishes an Architecture Decision Records (ADR) system for the Rhiza project to systematically document important architectural and design decisions. It creates the foundational structure with a template and the first ADR that documents the decision to use ADRs itself.

Key changes:

  • Establishes ADR directory structure at docs/adr/ with index, template, and first decision record
  • Documents the rationale for using ADRs including context, consequences, and guidelines for future records
  • Updates main README to reference the ADR system and provide quick access to key decisions

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File Description
docs/adr/README.md Creates ADR index file with format guidelines, resource links, and instructions for creating new ADRs
docs/adr/0001-use-architecture-decision-records.md First ADR documenting the decision to adopt ADRs, including detailed context and consequences
docs/adr/0000-adr-template.md Provides standardized template for future ADR documents with consistent sections
README.md Adds new section linking to ADR documentation and highlighting the first ADR

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/adr/README.md

## Creating a New ADR

1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-your-title.md`
Copy link

Copilot AI Jan 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example command shows copying to "0002-your-title.md", but the instruction to "Use the next available 4-digit number" in step 2 already makes this clear. Consider updating the example to use a more realistic title like "0002-example-decision.md" for consistency with the naming pattern shown elsewhere in the documentation.

Suggested change
1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-your-title.md`
1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-example-decision.md`

Copilot uses AI. Check for mistakes.
@HarryCampion
Copy link
Collaborator

HarryCampion commented Jan 11, 2026

This is cool, can we add an agentic workflow for this to autogenerate?

make ADR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@HarryCampion HarryCampion Awaiting requested review from HarryCampion

@markrichardson markrichardson Awaiting requested review from markrichardson

@tschm tschm Awaiting requested review from tschm

Assignees

@tschm tschm

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Start to maintain an ADR

3 participants

@HarryCampion @tschm